<?php
// $Id: Value.interface.php 73 2007-02-12 03:45:43Z tswicegood $

/**
 * This file contains {@link Value} which is part of the PHP Content Repository 
 * (phpCR), a derivative of the Java Content Repository JSR-170, and is
 * licensed under the Apache License, Version 2.0.
 *
 * This file is based on the code created for
 * {@link http://www.jcp.org/en/jsr/detail?id=170 JSR-170}
 *
 * @author Travis Swicegood <travis@domain51.net>
 * @copyright PHP Code Copyright &copy; 2004-2005, Domain51, United States
 * @copyright Original Java and Documentation 
 *  Copyright &copy; 2002-2004, Day Management AG, Switerland
 * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, 
 *      Version 2.0
 * @package phpContentRepository
 */


/**
 * Load the {@link phpCR} library file(s)
 */ 
require_once(dirname(__FILE__) . '/phpCR.library.php');


/**
 * A generic holder for the value of a {@link Property}.
 *
 * Can be used without knowing the exact type (string, double, stream etc.)
 *
 * @see BaseValue, BinaryValue, BooleanValue, DateValue, DoubleValue, LongValue,
 *  ReferenceValue, SoftLinkValue, StringValue
 * @author PHP - Travis Swicegood <travis@domain51.net>
 * @copyright Copyright &copy; 2004-2005, Domain51
 * @package phpContentRepository
 */
interface Value
{
   /**
    * Returns the type of this Value.
    * One of:
    * <ul>
    *   <li>{@link PropertyType::STRING}</li>
    *   <li>{@link PropertyType::DATE}</li>
    *   <li>{@link PropertyType::BINARY}</li>
    *   <li>{@link PropertyType::DOUBLE}</li>
    *   <li>{@link PropertyType::LONG}</li>
    *   <li>{@link PropertyType::BOOLEAN}</li>
    *   <li>{@link PropertyType::SOFTLINK}</li>
    *   <li>{@link PropertyType::REFERENCE}</li>
    * </ul>
    *
    * @see PropertyType
    *
    * The type returned is that which was set at property creation.
    *
    * @return int
    */
    public function getType();
    
    
   /**
    * Returns the string representation of this value.
    *
    * Unlike {@link Property::getString()}, this method throws a 
    * {@link ValueFormatException} if conversion is not possible.
    *
    * @return string
    *   A string representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to string
    *   (since everything can be converted to string, this should never happen) 
    *   or the value is NULL (i.e., empty).
    * @throws {@link IllegalStateException}
    *   If {@link getStream()} has been called previously at least once.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getString();
    
    
   /**
    * Returns the float/double representation of this value.
    *
    * Unlike{@link Property::getDouble()} this method throws a 
    * {@link ValueFormatException} if conversion is not possible.
    *
    * PHP Specific: PHP does not implement a double, but instead uses
    * a {@link http://us2.php.net/manual/en/language.types.float.php float}. 
    *
    * @return float 
    *   A float representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to 
    *   float or the value is NULL (i.e., empty).
    * @throws {@link IllegalStateException}
    *   If {@link getStream()} has been called previously at least once.
    *
    * @throws RepositoryException If another error occurs.
    */
    public function getDouble();
    
    
   /**
    * Returns the InputStream representation of this value.
    *
    * Unlike {@link Property::getStream()} this method throws a 
    * {@link ValueFormatException} if conversion is not possible.
    *
    * Please note that calling {@link getStream()} repeatedly will always
    * return the same InputStream object.
    *
    * @todo Determine if it is possible to implement this in PHP.
    *
    * @return object
    *   A {@link InputStream} representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to 
    *   {@link InputStream} (since everything can be converted to string, this 
    *   should never happen) or the value is NULL (i.e., empty).
    * @throws {@link IllegalStateException}
    *   If any getter methods other than {@link getStream()} and 
    *   {@link getType()} have been called previously at least once.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getStream();
    
    
   /**
    * Returns the {@link Calendar} representation of this value.
    *
    * Unlike {@link Property::getDate()} this method throws a
    * {@link ValueFormatException} if conversion is not possible.
    *
    * @todo This may need to be adjusted, as PHP does not have a default 
    *   Calendar object.  Alternatives might include returning the results of a
    *   date(), a timestamp, or possibly creating a basic Calendar object.
    *
    * @return object
    *   A {@link Calendar} representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to 
    *   {@link Calendar} or the value is NULL (i.e., empty).
    * @throws {@link IllegalStateException} 
    *   If {@link getStream()} has been called previously at least once.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getDate();
    
    
   /**
    * Returns the int/long representation of this value.
    *
    * Unlike {@link Property::getLong()} this method throws a
    * {@link ValueFormatException} if conversion is not possible.
    *
    * PHP Specific: PHP does not implement a long, so this
    * method should return an 
    * {@link http://us2.php.net/manual/en/language.types.integer.php integer}
    *
    * @return int/long
    *   An integer representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to
    *   integer or the value is null (i.e., empty).
    * @throws {@link IllegalStateException} 
    *   If {@link getStream()} has been called previously at least once.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getLong();
    
    
   /**
    * Returns the boolean representation of this value.
    *
    * Unlike {@link Property::getBoolean()} this method throws a
    * {@link ValueFormatException} if conversion is not possible.
    *
    * Same as level 1.
    *
    * @return bool
    *   A boolean representation of this value
    *
    * @throws {@link ValueFormatException}
    *   If, due to its type or format, this value cannot be converted to 
    *   boolean or the value is null (i.e., empty).
    * @throws {@link IllegalStateException}
    *   If {@link getStream()} has been called previously at least once.
    * @throws {@link RepositoryException}
    *   If another error occurs.
    */
    public function getBoolean();
}

